Static site generators emit the markdown source of a page as a sibling of
its directory index — `about.md` next to `about/index.html`. The file is
already on disk; the server just never looked for it.

Now a request whose Accept header names text/markdown is served that
sibling. Without this an agent can only discover the markdown by reading
the <link rel="alternate"> inside the HTML document it was trying not to
download. Measured on a real zop.dev build, the same page is 15-96x
smaller as markdown (a changelog entry: 145,354 bytes of HTML vs 1,512).

Only explicit media types count. A browser sends `*/*;q=0.8`, which
matches text/markdown by the letter of RFC 9110, so matching wildcards
would serve raw source to every human visitor; q-values are honoured, so
a client that ranks markdown below HTML still gets HTML. The lookup falls
through untouched when the client did not ask or the .md is absent, so
nothing an existing deployment serves today changes.

Vary: Accept is set on every response — without it a CDN can hand an
agent's markdown to the next browser that asks for the same URL.

.md is registered with the mime package explicitly: Go's built-in table
has no entry for it and a scratch base image has no /etc/mime.types, so
http.ServeFile would otherwise sniff the file and label it text/plain.

Verified end to end against a 5,933-page build: agents get markdown,
browsers get HTML, pages without a .md still return 200, and direct .md
requests are unaffected. Handler and negotiation are at 100% statement
coverage.

`_headers` is the Netlify / Cloudflare Pages convention: a file at the
root of the published directory listing path patterns and the response
headers to send for them. Static site generators emit it expecting the
host to honour it, and a host that ignores it fails in the worst way —
the file looks authoritative in the repo while nothing it declares has
ever reached a browser.

https://zop.dev, served by this project, has shipped a 2,437-byte
_headers for months. Measured against the live site, not one of its
rules was in effect:

  X-Frame-Options: DENY                    absent
  X-Content-Type-Options: nosniff          absent
  Referrer-Policy                          absent
  Permissions-Policy                       absent
  Cache-Control on /_astro/* (immutable)   absent entirely

That last one matters twice over: content-hashed bundles that could be
cached for a year were being served with no caching directive at all.

Rules are parsed once at startup. A published directory without a
_headers file yields no rules, so an existing deployment is
byte-for-byte unchanged.

All matching rules contribute in file order, so a later specific block
overrides an earlier catch-all, matching upstream precedence. Malformed
lines are skipped rather than failing the file: one bad rule should not
cost a site every other header it declares. Headers are applied before
anything writes, so they cover hits, misses and the SPA fallback alike —
a 404 that leaks framing protection is as exploitable as a 200 that does.

Note for operators: if a reverse proxy sits in front of this server, it
may set some of these itself. Strict-Transport-Security is the usual
one (ingress-nginx sends max-age=15724800, no preload, with replace
semantics), and where it does it will keep winning; the other five
headers rarely have a proxy counterpart and take effect immediately.

Verified against a real 5,933-page build: 22 rules load, and the expected
headers appear on pages, hashed assets, the root and robots.txt. Compared
891 request/response pairs against origin/main — zero body differences,
zero unintended differences. Handler and parser at 100%/96% statement
coverage; golangci-lint output identical to origin/main.

…long

Three header changes reached responses that cannot benefit from them. Each was
found by diffing the real binaries against origin/main rather than by reading
the diff — the earlier comparison covered status, Content-Type and body only,
so nothing had ever checked Vary or Cache-Control.

Vary: Accept was sent on every response, including the hashed bundles under
/_astro/ that the same _headers file marks immutable. Only an extensionless
route can resolve to a .md sibling, so everything else was keying caches on a
header that cannot change what they return — the cost landing precisely on the
responses this server most wants cached. It is now gated on the same condition
resolveFilePath uses to negotiate, and negotiable() is the one definition of
that condition so the two cannot drift apart.

A miss still varies whatever the path looks like, because a miss is answered in
markdown whenever the client asked for it — including for extensions that never
negotiate on a hit. Without that a cache can hand an agent the HTML shell it
stored for a browser.

A site's Cache-Control reached its 404s. `/*.html` with max-age=300 meant a
file merely not propagated yet during a deploy was pinned into every cache
downstream for the rule's lifetime. Cache directives are now dropped on a miss.
The security headers still apply — a 404 that leaks framing protection is as
exploitable as a 200 that does — and the SPA fallback keeps its caching, since
that is a real route being served, not a miss.

Directly requested .md files were relabelled text/plain -> text/markdown.
Bodies were identical, which is how it read as a no-op, but browsers render
text/plain inline and download text/markdown: every existing .md link on a site
would have turned into a download prompt. The explicit type is now set only for
a negotiated response, which is the case that needs it — Go's MIME table has no
.md entry and distroless has no /etc/mime.types.

Verified against base and patched binaries on the same build across 13
path x Accept combinations, comparing status, Content-Type, Vary, Cache-Control,
X-Frame-Options, Content-Length and body SHA-256. The only changed or removed
field in the whole matrix is the one intended negotiation; every other delta is
a header the site's own _headers file declares. Six mutations go red: Vary
unconditional on hits, no Vary on a miss, the Cache-Control strip removed, the
markdown Content-Type unscoped, and negotiable() ignoring either the extension
or the root.

golangci-lint output is identical to origin/main (4 findings, all pre-existing).

…d for real

Four items from review, all confirmed against the code before acting.

The empty-config test was vacuous, and the mutation narrative made that worse
rather than better. It re-implemented the fallback in its own body:

    got := tt.value
    if got == "" { got = tt.fallback }
    assert.Equal(t, tt.want, got)

which passes by construction and never touches main.go. Deleting both guards
from main() left the suite green — the one bug that commit fixes had no test at
all. The resolution now lives in resolveOrDefault, taking the narrow config
interface it needs, and is table-tested through the real function against a fake
whose keys are present-but-empty, which is the distinction that matters and the
one configs/.env actually ships. Removing the guard now fails.

The SPA fallback could serve a negotiable route without Vary: Accept. With
foo.md on disk and no HTML page beside it, markdown clients take the hit path
and browsers land on the shell, so one URL yields two bodies while only one of
them said it varies — a shared cache could hand the shell to an agent.
Reproduced against a running server before fixing.

Vary is now advertised through one helper, which keeps Add over Set: a site's
_headers may declare its own Vary and Set would discard it, while repeated field
lines are combined by caches, so a declared `Vary: Accept-Encoding` plus ours
reads as `Accept-Encoding, Accept`. What the helper adds is idempotence, so a
site that already named Accept does not end up with `Accept, Accept`.

The README documented neither content negotiation nor _headers, though it is the
repo's only doc surface and already carries a behaviour contract. Shipping
_headers support undocumented is the same failure this PR argues against for
_headers itself. Both are now described, including the Vary scoping, the
Cache-Control-on-miss rule, `.well-known`, and the empty-value config fallback.
Every claim in those sections was checked against a running server rather than
written from memory: pattern anchoring both ways, no Vary on assets, a
site-declared Vary surviving, Cache-Control withdrawn from a miss while
X-Frame-Options is not, the legacy text/x-markdown spelling, and the startup log.

Mutation coverage extended to all of it: resolveOrDefault ignoring empty, the
SPA fallback dropping Vary or advertising it unconditionally, and the
idempotence guard removed. The unconditional case is only observable for a root
with no index.html, so that shape is pinned explicitly rather than left as an
unverified assertion. Suite green under golang:1.26 with media-types installed;
golangci-lint unchanged at 1 finding against origin/main's 4.